Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 001 / comsh17.arc / COMSH17.DOC < prev next >

Wrap

Text File | 1985-06-03 | 84.3 KB | 4,229 lines

Comsh ----- A Communications Shell for the IBM PC Tandy 2000 And a cast of thousands Document Revision: 1.2 (July 15, 1984) Software Revision: 1.7 (July 11, 1984) Copyright 1984 by Charles McGuinness Section 1: Introduction Section 2: Program Startup Section 3: Commands Section 4: Scripts Section 5: Use of Comsh with CIS - 1 - Introduction Introduction: [Scope of this manual] This document is the COMSH *reference* manual; it attempts to be complete, instead of breezy or tutorial in nature. Support for this program -- including help, hints, and the like -- can be found in the Programmer's SIG on the CompuServe Information Service (page PCS158). [Introduction to COMSH] COMSH stands for "COMmunications SHell". The flavor and nature of COMSH is derrived from the UNIX(tm) environment, but it has been adapted to a communications environment. There are roughly two things COMSH tries to do: (1) COMSH attempts to provide a collection of tools that will be useful while communicating, but not directly relating to communications. Thus, for example, it is possible to search and retrieve information from the computer COMSH is running on while being logged into a remote computer. This allows for electronic note keeping, etc. (2) COMSH attempts to provide a collection of tools that are directly useful in automating or semi-automating communications with a remote host. For example, it is possible (and has been done!) to get COMSH to log into CompuServe, visit various SIGs, retrieve messages, post replies, and log off -- all without supervision. [Philosophy of operation] When you first invoke COMSH, you are running in command mode; COMSH expects you to tell it what to do. What you type at that point is not sent to the modem; rather, COMSH tries to interpret each line you type in as a command or command sequence of some sort. One of the commands, "COM", puts you into communications mode. When you are in communications mode, things are reversed from command mode. COMSH no longer tries to interpret you lines as commands; rather, each character you type is copied out to the modem immediately. Only when you press one of the function keys (or shifted/alted function keys) does COMSH perk up and try to make sense of your key stroke. - 2 - Introduction The function keys under communications mode are assigned one command line, which COMSH interprets like any other command; and, after executing the command, COMSH returns to the communications mode. Thus, you are able to program (the keys are [re]definable, see "SET") several command sequences into the function keys. Two special function keys are available in communications mode: F10 and shift-F1. F10 presents you with the COMSH command prompt (%), and allows you to type one command line in. That command line is executed, and you are immediately returned to command mode. Shift-F1 causes you to exit communications mode back to command mode. [screens] If your computer has the appropriate hardware (i.e., a Color Graphics adapter), you can utilize your four text screens under COMSH (See STTY). - 3 - Program Startup Program Startup [Invoking Comsh] Comsh is invoked just like any other PC/MS-DOS program: you simply type "comsh" at the DOS prompt (which is usually "A>" or similar). For example: A> comsh When Comsh first starts up, it looks for a file "profile.csh" in the default path on the default drive (if you have MS/PC-DOS 2.xx) or just on the default drive (MS/PC-DOS 1.xx). If this file is found, it is executed as a script (see the section on scripts; a script is merely a text file which has a sequence of Comsh commands that are executed). The purpose of having "profile.csh" is to allow you to set default values for any of Comsh's parameters (e.g., touch tone or pulse dialing), and to allow you to have Comsh take any initial actions you want (including, if you like, dialing into CompuServe and logging in!). There is another way to start comsh up; if, after typing "comsh" you type the name of a script (without the .csh extension), then comsh will execute that script immediately. For example, if you have a file called "login.csh" that had the sequence of commands necessary to log you into CompuServe, you could type: A> comsh login and Comsh would log you in immediately. - 4 - Program Startup [What to do once you're in Comsh] Unless you have things established (via a profile.csh file) to switch you into communications mode, the first thing you see in Comsh (following the banner) is the prompt: % This prompt (similar to MS/PC-DOS's A> prompt) lets you know that Comsh is waiting for a command. In the section that follows, commands and their usages are described in detail. Briefly, though, the most important command is "com": % com which tells Comsh to connect you to the modem. Until you execute this command, you are talking to Comsh -- not the modem and certainly not to CompuServe or anybody else. - 5 - Commands Commands The true power of Comsh lies in its command repertoire. All though the numerous commands can seem confusing (and certainly not "user friendly"), the power available to the user through these commands -- and through writing programs in the command language -- is Comsh's reason for being. Once you've mastered the commands, you will be able to get Comsh to do everything including fetch the (electronic online version) Sunday paper for you! As mentioned above, the prompt used by the communications shell is a percent sign (%). When you see this prompt, Comsh is awaitng your command. (Unless the computer you are connected too also uses % as its prompt, in which case you'd better know where you are...) While any command is executing (including scripts), a break key (control-scroll lock on the IBM PC, or control-break on the Tandy 2000) will stop everything and return you to either command mode or communications mode (depending upon which mode you were in when you executed the command). Command Syntax -------------- Every command issued to Comsh consists of the command name followed by a list of arguments to the command. Each argument is seperated from the others by a space. Should you wish to embed a space within an argument, you may enclose the entire argument in quotes ("). For example, if you issue the following echo command: echo hello there you have supplied two arguments ("hello" and "there") to the echo command. If, however, you type: echo "hello there" you have supplied one argument ("hello there") to the echo command. It is important to remember that the quotes are stripped off before being passed to a command; thus, both of the above commands will result in hello there being printed on the terminal. However,: echo Hello There and echo "Hello There" do not return the same result; the excess spaces between Hello and There are stripped in the first case and preserved in the second case. - 6 - Commands The reasons for this difference may seem hazy at first; for now, it is best to just note that Comsh eats extra spaces unless the spaces are preserved by quotes. You may type in several commands on one line; to do this, you must seperate each command with a semicolon. For example, the following echo Directory of device A: ; ls a will cause the message "Directory of device A:" to be printed on the screen followed by the directory of disk A:. You may embed special (e.g., control) characters in your arguments; the notation \c will be translated to control-C, while \m will be translated to control-M (a carriage return). In addition, \$ is translated to simply $, while \" becomes " and \\ becomes \. Variables --------- The communications shell keeps track of several variables during its life. These variables can be used for many purposes, including function key assignment and argument passing to scripts (see SET). When an argument to a command starts with a dolar sign ($), the actual argument passed to the command is not $<whatever>, but the value of that variable. For example, let's say we've defined the variable myname to be "charles". Then, if we say echo $myname the communications shell will respond with: charles and *not*: $myname Several variables are "magic". Specifically, the variable $ (which is referenced by "$$") is used by scripts to indicate how many arguments have been passed to them. The variables 0 through 9 (i.e., $0 through $9), represent the arguments to the script. Variable 0 always is the name of the currently executing script. These variables are local during the execution of scripts, and are preserved during nesting of script execution (see section on Scripts). An - 7 - Commands amusing example of a script that uses its arguments is: rm $0 which is a one line script that automatically deletes itself. The variable $TIME returns the current time of day (in HH:MM:SS format), while the variable $DATE returns the current date (in the format MM-DD-YY). The variable $FREE returns the number of free bytes left in the capture buffer, while the variable $SIZE returns the number of bytes in the capture buffer. The variable $RESULT is set to zero when a command completes successfully, while it is non-zero if there was an error in the command's execution. *** WARNING *** In COMSH 1.7, variable names should not be longer than 7 characters. Longer names will be accepted, and can be referenced, but they produce undesirable side-effects (viz., garbage in the variable symbol table). Following is an aphabetical list of all commands currently supported by the communications shell. - 8 - Commands: add, sub, mul, div add, sub, mul, div SYNTAX: add <varname> <value> sub <varname> <value> mul <varname> <value> div <varname> <value> DESCRIPTION: These four commands provide a means for Comsh scripts to manipulate numeric and time data. Each command performs the operation specified between the contents of the variable <varname> and <value>, and stores the result back in <varname>. For example, let's say the variable "count" has "1" in it. Then, add count 1 would result in $count returning 2 afterwards. Likewise, if "count" has "2" in it, mul count 5 would result in $count returning 10 afterwards. A special feature of these operators is that if the <varnmame> is in the format <days>:<hours>:<mins>:<secs> (where days and hours are optional), the result of the operation will be stored in that format. For example, suppose the variable "now" has the value "10:42:30". If we say: add now 65 "now" will then contain "10:43:35". Or, if "now" has "14:32", saying: add now 1:03 will result in "now" containing "15:35". Conversely, if <varname> is in a simple numeric form, but <value> is in DD:HH:MM:SS form, <value> is converted to seconds first and then added (or subtracted, multiplied, divided) into <variablename>. For example, let's say that "grue" has the value "55". Saying: add grue 1:00 will result in "grue" having "115". - 9 - Commands: add, sub, mul, div The value of all this is perhaps best illuminated in the following short script. : sleepuntil <time> : This script sleeps until the specified time, unlike Comsh's : sleep, which sleeps for a specified number of seconds. set stime $1 : this next line should return the amount of time to sleep. sub stime $TIME : if it is negative, then we're being asked to sleep until : tomorrow sometime if !greater 0 $stime ok : it is negative ... add one day's worth of time in to make : it postive again add stime 1:0:0:0 : ok set foo 0 : convert from d:h:m:s format to just seconds add foo $stime : and sleep until then! sleep $foo - 10 - Commands: Append Append SYNTAX: ap <file1> <file2> DESCRIPTION: The "ap" command appends the contents of file1 to the end of file2. This is useful for appending "session" logs (files which have been captured just this last session) to the end of more permanent log files. The destination file (<file2>) is actually appended to; that is, the append process does not create a third, intermediate file. This can cause some problems if the disk decides to become full (or croak) during the append process, as <file2> will have part of <file1> appended to it, but not all of it. Caveat Appendix. SEE ALSO: apl, cp, mv - 11 - Commands: apl apl SYNTAX: apl [-n] <file> <text> DESCRIPTION: The append line command is used to append one line of text to a specified file. The file is created if it does not exist. For example, apl foo.bar "This is a test!" will append the line "This is a test" to the end of the file "foo.bar" (Please don't groan at the metafilenames.) The "-n" option causes the command to not place a crlf at the end of the line being writen; this is useful if you want to build up the line in several apls (but this approach is slow). For example, "Hello There" can be writen out to the end of foo.bar by executing: apl -n foo.bar "hello" <-- Note -n apl foo.bar " there" <-- Note space! <-- Note no -n SEE ALSO: ap, read, set, who.csh - 12 - Commands: captodisk captodisk SYNTAX: captodisk <filename> captodisk DESCRIPTION: The captodisk command is used to start and stop the direct capturing of input data to a disk file. If you specify: captodisk <filename> all subsequent incoming data is writen out to the file specified (assuming that it could be opened). If you just specify: captodisk any previous capturing to disk is stopped, the file closed, and no capturing to disk will take place (until the next captodisk <filename> command). One interesting application of this is to say: captodisk prn: which will cause a transcript of all data received to be printed. Note that this make cause delays on your screen, as the screen I/O routines wait to get their data until after captodisk has finished writing its data. A pause while the printer buffer empties will cause the screen output to pause too. But, so long as you have interrupt handling (e.g., a Tandy 2000 or IBM PC using COMBIOS), you won't lose any data. SEE ALSO: close, open, write, reset - 13 - Commands: cat cat SYNTAX: cat <file> [<file> ...] DESCRIPTION: The "cat" command is used to type the contents of a file out on the terminal's screen. If you want to stop the display of a cat prematurely, the break key will stop cat ... along with any executing scripts, etc. As a general rule, if you want to browse through a file, the more command works better. SEE ALSO: more - 14 - Commands: cb cb SYNTAX: cb [-s | -s0 | -s1 | -s2 | -s3] DESCRIPTION: The "cb" command is used to place the communications shell into "cb" mode. This mode is designed to work with CompuServe's CB, CO, and EIS Conference Room. The purpose of this command is to keep your screen uncluttered and organized while you are talking. Your input proceeds uninterrupted on the bottom line while incoming messages arive just above your text. When you type return, your message is merged in with the incoming messages in a clean manner. If a line is received from CIS/EIS that is longer than 80 characters long, the CB mode will perform word wrapping to the next line -- and indent the next line by a few spaces to show that the line is a continuation of the previous message. OPERATION: In order for cb mode to be particularly useful, you must be running half duplex (i.e., stty -echo). Since most terminals run in full duplex, with the host system echoing each character as it is typed, it will probably take a bit of effort to get the system to switch to half duplex. On CIS, the easiest way is to issue the "HALFD" command while in the personal file area (the "OK" prompt). Once you've done that, you'll also want to tell Comsh that you are running in half duplex mode; that can be performed by the command: stty -echo (note that you'll probably have to hit f10 first to get a Comsh prompt, and then give the "stty -echo" command). Two function key assignments are hardwired into cb mode. Alt-f1 will exit cb mode, and f10 will allow you to issue one Comsh command. OPTIONS: The various -s options (which are, of course, optional) determine which of the 4 screens will be used by cb. The "-s" optiion uses the default communications screen (screen 1), while -s0 through -s3 pick screens 0 through 3, - 15 - Commands: cb respectively. If no option is supplied, the current screen is used. BUGS: Switching screens mid CB-Session is rather awkward. CB mode doesn't work on 24 line screens (set by "stty 24"). Since CB mode waits for a <cr> to arrive from the host before displaying any part of a line from CIS, the /han command doesn't work too well. CIS sends out the "Handle name? " prompt without a <cr>, and so CB mode just sits there and waits for the <cr>. There are three solutions to this problem. (1) Drop back to "com" mode (either by alt-f1 or via f10/com), change your handle, and return to CB mode. (2) After you type /han, go ahead and type your handle without the prompt. When you type return, the prompt will scroll on by. Or (3) write a script to change your handle and don't worry about it... - 16 - Commands: cd cd SYNTAX: cd <path> DESCRIPTION: The cd command is used under DOS 2.x to change your current directory. Because Comsh uses DOS 1.x file calls exclusively (except for cd & pwd), it is necessary to be "in" the directory of any files you wish to read / write / create, etc. The cd command is, then, a limited DOS 2 support; if you have DOS 2, it provides you with access to all of your directories; if you have DOS 1, you aren't prevented from doing file I/O. Please note that this command is not the same as the DOS 2 cd; it does not print the path when there are no arguments. EXAMPLE: cd A:\Comsh\FILES SEE ALSO: pwd - 17 - Commands: clear clear SYNTAX: clear DESCRIPTION: The clear command clears the current screen. If you wish to clear a different screen, you will have to switch over to it first. - 18 - Commands: close close SYNTAX: close DESCRIPTION: The close command causes the capture buffer to be closed. After that, all incoming information is not saved until another open command is performed. SEE ALSO: open, write, cap - 19 - Commands: com com SYNTAX: com [-s<n>] DESCRIPTION: The com command switches the user into communications mode, i.e., anything the user types is sent out the rs232/modem port and anything received is sent to the screen. While in communications mode, the user has a few function key commands available to him; see the section on communications mode for further details. The -s option is used to determine which screen (of the 4) will be used initially for communications. If no screen is specified, the current screen will be used. The initial definitions for function keys are: F1 -- "more comsh.hlp" F2 -- "clear" F9 -- sends a control-o followed by a return F10 -- gives you a chance to execute one command Alt-F1 -- Returns to previous mode. SEE ALSO: switch - 20 - Commands: cp cp SYNTAX: cp <source> <dest> DESCRIPTION: The "cp" command is used to copy one file to another. For example, to copy "Comsh.exe" to "Comsh.bak" on drive B:, you would type: cp Comsh.exe b:Comsh.bak As an interesting note, it seems that the DOS copy command has some sort of protection scheme built into it; thus, certain files cannot be copied with it. While I don't want to promote Comsh as a copy protect defeat mechanism, the Comsh cp command has no such limitations... SEE ALSO: ap - 21 - Commands: dial dial SYNTAX: dial dial <name> dial <name> <service> DESCRIPTION: The "dial" command is used to auto-dial a hayes smart modem; it knows how to dial local numbers and can interface to various long distance services (like MCI or SPRINT or even AT&T!). The command has three forms of interest: (1) dial (2) dial <name> (3) dial <name> <service> (1) Merely instructs dial to list all of the various phone numbers you can call. (2) tells Comsh to dial the computer called <name> which is in your local dialing range. (3) tells Comsh to dial the computer called <name> long distance using the long distance phone company called <service>. At the current moment, the dial command knows only how to dial Hayes Smartmodem (and compatibles). Other modem types can will be added if/when the author of Comsh is told how to work them.... All dial does is to output the correct command to the modem to dial the phone; it does not check to see if the call was completed or not. Checking the success of a call can be done by setting up the appropriate patterns and waiting for one of them to occur (See the next section on scripts). The dial command defaults to touch tone dialing; see "stty -tt" for information on how to set the dial command up for pulse dialing. FILE FORMATS: In order to actually know where to call, the dial command needs to have at least one file on the default drive (in the default directory, for you DOS 2 users). This file must be called "PHONE.NUM". Phone.num is a text file, each line of - 22 - Commands: dial which contains one entry in the phone numbers database. The format of each line is: <name>:<phone-number>:<baud-rates>:<comments> For example, here's a short example: cis0:7584114:300:CompuServe 300 baud only cis1:7582090:1200,300:CompuServe 1200/300 pcbbsnyc:541-5975:1200,300:PC BBS in NYC mci:245-0355:1200,300:MCI Mail New York Node proshop:617-461-0174::Programmer's shop (7pm - 7am) pcbbsli:516-944-6712:300,1200:RBBS Long Island Notice that the long distance entries do not have a leading "1" (for long distance access). This is because not all long distance dialing services want that "1" before the area code. (MCI, for example, gags on a "1" before an area code). Of course, AT&T or your local operating company *will* want that leading "1" if you're going to dial via the conventional, costly route. In order to give each long distance service what they need, there is a "service" file which has two entries in it (each entry on a line to itself). The first entry contains the codes to prefix the phone number with; the second entry contains the codes to postfix the phone number with. Thus, for example, an ATT service file would look like: 1- The second line of the service file is blank because the phone number is the last thing that will be dialed (and thus there's no postfix). A sample MCI service file would look something like: 0000000,,,,11111- , Where "0000000" would be replaced with the local MCI access number and "11111" would be replaced with your MCI "password". The commas between the local MCI access number and the password tell the Hayes modem to pause; four provides a reasonable delay to allow MCI to answer. The second entry (just ",") is to provide a slight extra delay since MCI is sometimes slow in making a connection. In these examples, the service files would be called "ATT." and "MCI.". Thus, you could say: dial pcbbsli mci - 23 - Commands: dial to reach the pc bbs in long island using MCI. - 24 - Commands: echo echo SYNTAX: echo [-n] <text> DESCRIPTION: The echo command merely echoes any text after it to the screen. This is useful in printing prompts, message, etc. to the screen during the execution of a script. The "-n" operation cause the echo command to inhibit writing a <crlf> after the text; this is useful when you want to allow the user to enter a response on the same line as a prompt. EXAMPLES: echo This is a test will print... This is a test<crlf> echo -n This is a second test will print... This is a second text<cursor> NOTES: Echo takes each of its arguments, and outputs them seperated by one space. As pointed out earlier in this manual, echo hello there and echo "hello there" do not return the same results. If you want to echo information in fancy layouts, you should quote your arguments to be safe. SEE ALSO: read - 25 - Commands: exit exit SYNTAX: exit DESCRIPTION: Exit causes you to leave Comsh and return to the DOS command level. BUGS: If you've just downloaded 30k into your capture buffer, and type "exit", Comsh will gleefully eat your buffer and leave you with no means of recovering it. If you find this happens to you too often, create a short script called "quit.csh" that looks like this: : quit.csh if !same $SIZE 0 nowayjose exit : nowayjose echo "Please do something with the capture buffer." Then use "quit" instead of "exit" as your normal means of leaving Comsh. - 26 - Commands: fclose, fgets, fopen fclose, fgets, fopen SYNTAX: fclose fgets <varname> fopen <filename> DESCRIPTION: There are often times when it is necessary for Comsh to deal with text files a line at a time rather than all at once. Thus, for example, the "apl" command exists -- it allows you to write one line to the end of a file. Likewise, the fclose, fgets, and fopen command exist to allow you to read a file into Comsh variables one line at a time. The primary motavation behind these commands was to allow a simple script (given below) to be writen that would send a message to a SIG one line at a time, pausing for the ":" prompt before sending each line. The first command that should be used is the "fopen" command. This command prepares Comsh to read lines in from the named file. For example, if you say: fopen mymsg.txt Comsh will try to open the file "mymsg.txt". If the file exists, and can be opened, the variable "RESULT" will contain 0 (e.g., the command: if same $RESULT 0 foo will branch to the label "foo"). If the file does not exist, or cannot be opened for any other reason, "RESULT" will be non-zero. One a file has been fopened, lines can be read from the file one at a time via the "fgets" command. Asumming that we just did the fopen mymsg.txt command -- and that $RESULT is zero -- the command: fgets lvar will read the first line from the file mymsg.txt into the variable "lvar". Subsequent fgets will return the next lines in mymsg.txt. In order for you to know when you've reached the end of the file, fgets, like fopen, sets the variable "RESULT". If RESULT is zero immediately after fgets, then everythins is ok. If RESULT is non-zero, then end of file has been reached, and the contents of the variable fgets'ed into are garbage. - 27 - Commands: fclose, fgets, fopen Once you reach the end of the file, you should tell Comsh that you are through with the file. The command: fclose will have Comsh close the file; that allows you to fopen another file later. The following script implements a send to sig command that will send a text file to a sig one line at a time, pausing before each line for the sig editor's prompt: : usage: sendsig <filename> fopen $1 if !same $RESULT 0 nofile pattern reset pattern 0 ":\i" : loop fgets line if !same $RESULT 0 done send $line \m wait 10 if match 0 loop echo Time out! goto done : nofile echo No file $1 goto end : done fclose : end echo "End of Sendsig [28-Jun-84]" - 28 - Commands: goto goto SYNTAX: goto <label> DESCRIPTION: Goto is used within a script file to unconditionally goto a given label. If the label is not found, a nasty message is printed out and the script is terminated. - 29 - Commands: grep grep SYNTAX: grep <pat> <file> DESCRIPTION: Grep is a utility that prints out all lines in file <file> that contain the pattern <pat>. At the moment, the pattern is simply a sequence of characters that must occur in a line from <file> in order for that line to be printed. EXAMPLES: If the following three lines are in the file night.day: this is a test And so is this Line 3 is another test Then: grep "this" night.day would produce: this is a test And so is this While: grep "test" night.day would produce: this is a test Line 3 is another test - 30 - Commands: if if SYNTAX: if [!]match <pattern> <label> if [!]same <arg1> <arg2> <label> if [!]fexist <file> <label> DESCRIPTION: The "if" command is used to make conditional branches within a script. The if command provides six conditions that can be tested, and the brach to <label> is taken if the condition is true. The specific conditions are: match <pattern> This condition tests to see if the "wait" command terminated because pattern number <pattern> was found. A match of pattern -1 indicates that a time out occured. !match <pattern> Like the "match" condition, except the branch is taken if pattern <pattern> *wasn't* the reason for wait to terminate. same <arg1> <arg2> This condition tests to see if <arg1> is the same as <arg2>. Normally, one or both of the arguments is a variable; a common test is to compare a variable to a constant. If the two arguments match, the branch is taken. !same <arg1> <arg2> Like "same", excpet the branch is taken if the two arguments don't match. fexist <filename> This condition is TRUE (i.e., the branch is taken) if the file <filename> can be opened for read access (which is taken to mean that the file does exist). Thus, before a script opens a file, it can test for the file's existance and branch to an error routine if the file does not exist. !fexist <filename> Like "fexist", but the branch is taken if the file does not exist. EXAMPLES: if same $1 -add do-add if !fexist mydata.txt no-file if match 0 got-match - 31 - Commands: ls - 32 - Commands: ls ls SYNTAX: ls [<drive>] DESCRIPTION: The "ls" command lists the files on a given drive (or the default drive, if no drive is specified). The ls command will only list the files in the current directory (DOS 2.0), and does not display entries for any directories or special files. EXAMPLES: ls <-- Lists directory on default drive ls b <-- List directory on drive b SEE ALSO: cd, pwd - 33 - Commands: more more SYNTAX: more <file> DESCRIPTION: The more command prints out the contents of a file like cat, but pauses every screenful to allow you to read it. Every 22 lines, the "--MORE--" prompt is displayed; if you type a return, you get one more line; if you type a space, you get a screenful. If you type control-c, you'll stop the display. BUGS: The use of control-c is history; the break key should be substituted for consistency. SEE ALSO: cat - 34 - Commands: mv mv SYNTAX: mv <file1> <file2> DESCRIPTION: The mv command renames <file1> to <file2>. BUGS: You can't specify path names, and so moves from one directory to another don't work. SEE ALSO: cp - 35 - Commands: open open SYNTAX: open DESCRIPTION: Open opens the capture buffer; all characters received after the execution of the open command will be stashed away. However, when Comsh is in command mode -- or executing a command -- it ignores any data coming in the serial port, and thus does not capture it. The only exception to this is the "wait" command, which captures any data that comes in while it is waiting. If the "wrapbuf" is set to 0 (most likely because you haven't issued a wrapbuf command), Comsh will print funny messages out as the buffer starts to get full. When the buffer is completely full, an automatic "close" will be performed. If, on the other hand, a wrapbuf is in effect, the buffer just overwrites the oldest data as new data arrives when the buffer is full. SEE ALSO: close, reset, wrapbuf, write - 36 - Commands: pattern pattern SYNTAX: pattern [reset] [<number>] [<pattern>] DESCRIPTION: The pattern command is used to maintain the various patterns that will be matched by the "wait" command. The first form of the command is: pattern reset which causes all of the patterns to be reset (i.e., no patterns will ever match, and a wait command will either time out or hang forever). The second form of the pattern command is: pattern reset <n> where <n> is in the range 0..9, and is the number of the individual pattern to reset. Reseting a pattern causes it to no long be able to match anything. The third and final form of the command is: pattern <n> <pat> which defines what pattern (<pat>) pattern <n> will match. EXAMPLES: pattern reset <-- Zero all patterns pattern reset 3 <-- Prevent 3 from matching pattern 3 "This\m" <-- Match 3 on This<cr> - 37 - Commands: pwd pwd SYNTAX: pwd [<drive>] DESCRIPTION: The pwd command prints out the path of the current directory on the default drive (if no drive is specified) or on the specified drive. Note that this is a DOS 2 command only. EXAMPLES: pwd <-- Current directory on default drive pwd b <-- Current directory on drive b SEE ALSO: cd - 38 - Commands: read read SYNTAX: read <var> DESCRIPTION: The read command allows the user to type in one line of text, and then that entire line is stored in the specified variable. No parsing of the text is done. A useful technique for producing nice prompts is to do something like: echo -n "Please enter your name: " read name The cursor will pause at the end of "name: " waiting for the user to type his name in (as opposed to waiting at the begining of the next line). EXAMPLE: read foo <-- Afterwards, $foo will have the line typed in. - 39 - Commands: reset reset SYNTAX: reset DESCRIPTION: The "reset" command zeroes the contents of the capture buffer. No questions are asked, nor is any warning given if the capture buffer had data in it. If a "wrapbuf" is in effect, the reset command will turn that off. SEE ALSO: open, close, wrapbuf, write - 40 - Commands: rm rm SYNTAX: rm <file> [<file> ...] DESCRIPTION: The rm command deletes the file(s) specified. Note that the files must be in the current directory of the drive specified. "?" wildcards will work, but "*" wildcards will not. EXAMPLES: rm comsh.??? <-- Deletes COMSH.* rm this that the other <-- Deletes four files rm ???????.??? <-- You like living dangerously - 41 - Commands: see see SYNTAX: see DESCRIPTION: The "see" command allows you to see the current contents of the capture buffer without destroying them. See, like more, prints out several lines, and then pauses, waiting for you to type either a space (22 more lines, please!) or a return (one more line, if you would...). A control-c stops things where they stand. SEE ALSO: more - 42 - Commands: send send SYNTAX: send <text> DESCRIPTION: The send command transmits the specified text to the modem. One important use of this command is in conjunction with the fopen, fgets, and fclose commands. In some ways, send is like echo, in that it echos its arguments (but to the modem). However, unlike echo, send does not supply a return automatically; you must explicitly include a \m in your send to have a return transmitted. EXAMPLES: send \m <-- Sends a return send "hello\m" <-- Sends hello<cr> SEE ALSO: fclose, fgets, fopen, read, echo - 43 - Commands: sendf sendf SYNTAX: sendf [-l] <file> DESCRIPTION: The sendf command transmits a file out the modem port. If the "-l" option is specified, newline sequences are transmitted as <crlf>, otherwise newline sequences are transmitted only as <cr>. If the "stty s" command has been given, the you will see the echo back from the remote computer during a "sendf". A break key will abort a sendf mid-send. Sendf responds appropriately to XOFF/XON characters. However, when an interrupt drive serial port is being used (such as on the Tandy 2000 or COMBIOS on the IBM PC), then some problems may arise -- the buffering may cause Comsh not to be able to throttle its output quickly enough. The solution for this problem may be to write a script that sends lines via "send" at a slower rate. EXAMPLES: sendf test.fil <-- Sends test.fil, <CR>s only sendf -l test.fil <-- Sends test.fil with <CRLF>s SEE ALSO: send - 44 - Commands: set set SYNTAX: set set <var> <arg> set <option> DESCRIPTION: The set command serves two major purposes. The first purpose is to set and review variable settings. The second purpose is to control certain major Comsh operating conditions. In the first role, there are two major commands, the first of which is simply: set This causes all defined variables to be displayed. The second form, "set <var> <arg>", allows you to define or redefine variables. EXAMPLES (of variable manipulation): set foo "a test" <-- Sets $foo to a test set huh now <-- Sets $huh to now set yeh $foo <-- Sets $yet to "a test" OPTIONS: The second role of the set command, as mentioned above, is to set certain major options. Specifically, there are two classes of options. The first class is the script debugging facility. If you say: set DEBUG then every line of executing scripts will be printed out on the terminal as they are executed. This is to allow you to debug your scripts (obviously). If you say: set -DEBUG then the debuggin feature is disabled. The second class if set options are for selecting what kind of terminal Comsh is emulating. At the moment, Comsh knows about three terminal types: set VT52 <-- Emulate a VT52 set VIDTEX <-- Emulate CIS's VIDTEX set ANSI <-- Respond to ANSI escape sequences - 45 - Commands: set If you plan upon using "set VT52", please see the note under "stty 24". - 46 - Commands: sleep sleep SYNTAX: sleep <time> DESCRIPTION: Sleep causes Comsh to do nothing for <time> seconds. A break-key will abort a sleep mid-slumber. If you want to have Comsh sleep until a specific time, rather than having it sleep for a specific amount of time, you can use the sleepuntil script described in the section on the "add" command. - 47 - Commands: stty stty SYNTAX: stty <options> DESCRIPTION: The stty command is used to configure the communications parameters of Comsh. Any or all of the options may be present. The options, one by one, are: <speed> Specifies the baud rate Comsh runs at. Can be any baud rate supported by the ROM BIOS, including 300 and 1200. Initially is "300". [-]beep Specifies either that bell characters should make a noise (beep), or that they should be surpressed (-beep). -beep is useful for late night hacking or for politeness ... it also comes in handy if you're fond of typing binary files. [-]bsb Specifies whether backspaces should be destructive (bsb), or whether they should be non-desctructive (-bsb). A destructive backspace acts, in effect, like the sequence "backspace - space - backspace" (which is exactly how Comsh does it). [-]f Specifies "fudgemode", a not yet useful option. Initially is in non-fudgemode (-f). [-]s Specifies whether you get to watch all characters received during sendfs, sleeps, and waits (stty s), or whether these commands are quiet in their operation (stty -s). [-]tt Specifies whether touch tone dialing should be used (stty tt), or whether pulse dialing should be used (stty -tt). Of course, this only applies to hayes smartmodems (and compatibles). [-]w Specifies whether terminal will respond to the VIDTEX switch to 40 column (wide) mode command. CIS does this an awful lot, and leaves terminals in 40 col mode when it shouldn't. Initally is "-w", not allowing 40 column mode. - 48 - Commands: stty 7 | 8 Specifies whether 7 or 8 bit characters should be used. 8 bit characters allows IBM PC graphics characters to be received. Initially set to 7. Note that this is not the transmitted and received word size, but whether Comsh "ands" all incoming data with 127 or not. (see word7 | word8). 1 | 4 Specifies whether Comsh tries to use one screen exclusively (the "1" option), or will allow you to use (and it to use) four text screens (the "4" option). 24 | 25 Specifies whether Comsh gives you a 25 line screen (initial value) or a 24 line screen (stty 24). There is one primary use for this command: when running in VT52 emulation mode (see "set VT52"), you often need to have a 24 line screen to be fully compatible. Thus, it may be necessary to say both "stty 24" and "set VT52" to be fully VT52 compatible. [-]echo Specifies whether the remote host is echoing characters. "-echo" means the remote host does not echo, "echo" means the host does echo. Initially set to "echo". odd even none Each of these three (mutually exclusive) options selects the parity Comsh will use. "none" is the initial choice. word7 word8 Word7 tells Comsh to transmit and receive 7 bit words, while word8 (the initial choice) tells Comsh to tranimit/receive 8 bit words. stop1 stop2 Stop1 tells Comsh to transmit/receive 1 stop bit per character, while stop2 tells Comsh to transmit/receive two stop bits per character. "stty stop1" is the initial value. com1 com2 Many IBM PCs have two serial ports, named "com1" and "com2". "stty com2" tells Comsh to talk to the world via the com2 port, while "stty com1" (the initial choice) tells Comsh to talk via the com1 port. - 49 - Commands: stty EXAMPLES: stty 300 echo 4 Means: Run at 300 baud, expect a remote echo, and allow use of the four text screens of the CGA. - 50 - Commands: switch switch SYNTAX: switch <screen> DESCRIPTION: Switches the active screen to screen <screen>. The screen specified must be in the range 0..3. Note that the "stty 4" command must have been given before the switch command has any effect. If "stty 4" has not been executed, then switch acts line a no-op. - 51 - Commands: wait wait SYNTAX: wait [<max time>] DESCRIPTION: The wait command is used to wait for one of the defined patterns (see patter command) to be spotted in the input stream. If the <max time> argument is specified, wait will wait no more than <max time> seconds before giving up. If the wait does give up, then pattern -1 is "matched" (See "if match" for more details). A break will cause a wait to terminate early (as well as stopping all scripts that are executing...). SEE ALSO: if, pattern - 52 - Commands: wc wc SYNTAX: wc <file> DESCRIPTION: The wc command reports the total number of characters, words, and lines in the file <file>. EXAMPLE: When I said: wc comsh.doc I was told: 4228 lines, 13917 words, 82019 chars (AAAAARRRRRRRGGGGGGGHHHHHHH! Did I type all that???) BUGS: wc isn't the quickest thing. Don't wc if you need the answer yesterday... I think wc counts <crlf> as one character. - 53 - Commands: wrapbuf wrapbuf SYNTAX: wrapbuf <size> DESCRIPTION: Normally the capture buffer mechanism in Comsh will start griping when the buffer gets close to full and eventually closes itself when it is full. It does this so that any data you have captured doesn't get lost (at the expense of new data arriving after the capture buffer gets full). However, you can tell Comsh to manage its capture buffer so that it "scrolls" off the oldest data in favor of the newest data when it gets close to full. Thus, the capture buffer won't close when it gets full -- it'll just dump the oldest data to make room for the incoming data. The wrapbuf command is used to effect a transition between these two modes of operation. If you say: wrapbuf 0 Comsh will act in the normal, default way -- closing the capture buffer when it gets full. But, if you say (for example): wrapbuf 10000 Comsh will keep the ten thousand most recently received characters in the capture buffer. Any number between (but not including) 0 and $SIZE-4096 will work well for the wrapbuf factor. if you pick something between $SIZE-4096 and $SIZE, you'll encounter the "buffer getting full" warnings when you first start to fill the buffer (let's call this a ``feature''). The reset command sets the wrapbuf factor back to zero, so be careful. - 54 - Commands: write write SYNTAX: write <file> DESCRIPTION: The write command writes the contents of the capture buffer out to the file <file>. The write command actually appends the capture buffers contents to the file, so that if the file already exists the old contents will be preserved (though extended a bit). A destructive write can be had by saying: rm <file> ; write <file> If you're really lazy, you could even put that into a script... SEE ALSO: close, open, reset - 55 - Commands: xmodem xmodem SYNTAX: xmodem <option> <file> DESCRIPTION: The xmodem command is used to initiate an xmodem transfer between the local and remote computers. The options are: -s <-- Send the file <file> -rb <-- Receive the file <file> / binary -rt <-- Receive the file <file> / text The difference between the -rb and -rt options is that the -rt option causes all control-Zs (CPM end of file characters) to be swallowed and not writen out to the file. This is useful, as MSDOS keeps an exact character count of file sizes and so ^Zs are wasteful. Notes on using xmodem with CIS: Normally, there is no reason to do xmodem file transfers to/from CIS; the A protocol works better. However if you do try xmodem with CIS, be advised that there exists (at the time of this writing) a minor incompatibility between CIS and Comsh. Comsh pads the last record transmitted to CIS with control Zs, while CIS expects to see records padded with nulls. Thus, text files uploaded to CIS often end up with lots of control Zs at the end -- an annoying, though mostly harmless condition. Other modem programs (like "umodem" under Unix) will strip control Zs from text files. - 56 - Commands: : <label> : <label> SYNTAX: : <label> DESCRIPTION: This is the format for a target of a goto or if. Specifically, a label consists of a colon (:) followed by *one* space ( ) followed by the actual label. Labels also have another use in scripts. Labels can be cleverly used to insert comments into a script: When Comsh encounters a label in the middle of a script, it just ignores it (that is, any line starting with a ":" is ignored). So, you can stick labels like: : Start of script foobar in the middle of scripts, and they'll have no effect, save for the delay it takes to read the next line of the script. - 57 - Scripts Scripts [Introduction] One of COMSH's most powerful features is the ability to write "programs" in a simple interpretive language. These programs, better called scripts, are simply lists of COMSH commands to execute, and use COMSH's very simple branching ability. [How do scripts get invoked?] Whenever COMSH receives an illegal command (either from you or another script), it checks to see if there is a file of the form <command>.csh on the default drive in the default directory (Dos 2). If there is such a (text) file, COMSH then reads commands from this file instead of from the terminal. [Arguments to scripts] Scripts can accept up to 9 arguments (see discussion in the introductory section). The arguments, $1 through $9, are local to the script, and are preserved through calls to other scripts. [Commands in scripts] All of the commands used by scripts are described in the commands section of this document -- and some of those commands (if, goto, : <label>) are intended specifically for use within scripts. As the commands that can be used have already been described, this section will present some example scripts with detailed explanations in hope of conveying the power and flavor of scripts. [Stopping Scripts on a dime] If, while you are executing a script, you don't line the way things are going, hitting the break key (control-scroll lock) will stop *all* executing scripts and return you to command more or communicatons mode (depending upon where you were when you started the command). - 58 - Scripts [who.csh] The "who" command, as implemented in a script, is useful for maintaining an online database of people's names and accounts. Specifically, the format of the script is either: who <pattern> or: who -add The first form looks for the <pattern> in both names and ppns, allowing you to say something like: who Charles and: who 76703,373 The second form of the command is used when you have somebody's name and account to add to the database; the script then prompts for the necessary information. The database is kept in the file "who.dat" in the form: <account><tab><name> -- each line of the file has one entry giving the person's account and name. Following is the actual script along with a detailed discussion of its operation: if !same $$ 2 usage if !fexist who.dat nodata if same $1 -add addname grep $1 who.dat goto end : usage echo "usage: who <ppn> | <name> | -add" goto end : nodata echo "no file who.dat to search" goto end : addname echo -n "PPN to add:" read 1 echo -n "Name to add:" read 2 apl who.dat $1 "\i" $2 goto end : end - 59 - Scripts The first line of the script checks to see if the number of arugments passed (which is in the variable "$$") is equal to two (note that the name of the script, which is in the variable $0, counts as one argument). If there are not two arguments, the script branches to the label "usage", which will print out a message saying how to use the script. The second line of the script checks to see of the file "who.dat" exists. This file is the database of accounts and names, and if it is not present the script cannot look up names. If the file does not exist (!fexist), a branch is taken to the label "nodata", where a message about the missing file is printed. The third line of the script checks to see if the argument to the script is "-add" -- indicating that the user does not want to look up an account, but rather to add one. If the argument matches "-add", a branch is taken to "addname", where the name and account number will be added to the database. The fourth line actually performs the search using the "grep" command which is built into COMSH. Grep will report any matches found in the database. The fifth line branches to a common end point; scripts terminate by falling off the end. Lines six, seven, and eight are the usage reminder. Six is the target of the if branch; seven prints out the message giving the correct syntax for who; and eight braches to the end of the script. Lines nine, ten, and eleven provide the message when there is no "who.dat" file. Nine is the target of the if branch from earlier in the script; ten prints the message out; and eleven braches to the end. Line twelve is the label for the add new name routine. Line thirteen prints out a prompt asking for the ppn to add to the database; the "-n" argument causes "echo" to *not* output a CRLF at the end of the message so that the user's response will be on the same line as the prompt. Line fourteen causes COMSH to read a line of input in from the user and store it in variable 1 (which also happens to be a local variable, and points out that local variables can be re-assigned). - 60 - Scripts Line fifteen prints out the prompt asking for the name to add to the database; again, the "-n" argument prevents the CRLF from following the message. Line sixteen reads one line of input in from the user and assigns it to local variable 2; thus, $2 will have the name of the user to add to the database. Line seventeen actually updates the database. The "apl" command appends one line of text to a specified text file (in this case "who.dat"). The line following the file name ($1 \i $2) is expanded out to be "<ppn><tab><name>". Line eighteen takes a short branch to line nineteen, which is the end of the script. - 61 - Scripts [dialx] The "dialx" script is used to repetitively dial phone numbers (like bbses) so that you can (we hope) eventually get through to them. The syntax for dialx is: dialx <delay> <name> [<ld-service>] The first argument, <delay>, tells how long to pause between redials and is given in seconds. The second two arguments are exacty the same as supplied to the "dial" command, viz., the name of the computer you are trying to dial and, optionally, the long distance carrier to use. The source of dialx is: : dial to get thru to a busy number : dialx <delay> <number> [<service>] pattern reset pattern 0 "NO CARRIER" pattern 1 "CONNECT" : dodial if same $$ 4 longdial if !same $$ 3 usage echo Dialing $2 dial $2 goto well? : longdial dial $2 $3 : well? wait 45 if match 1 end echo Didn't get thru... sleep $1 goto dodial : usage echo usage: dialx <delay> <number> [<service>] : end The first two lines are "labels", but never used as such. Since COMSH ignores labels when it runs across them (only paying attention when it is looking for a specific one), labels make cheap ways to insert comments into a script. The next three lines are used to initialize the patterns used by this script. For reference, the Hayes smart modem returns one of two messages when you try to dial another computer with it: CONNECT if you succeed, and - 62 - Scripts NO CARRIER if you fail. Thus, two patterns are declared, one for each possible outcome. The pattern reset command gets rid of any other patterns that may happen to be already declared to COMSH, thus preventing errant pattern matches. (If pattern 2, for example, was matching for "CON", it would succeed before pattern 0 did, greatly confusing this script.). Once the patterns have been initialized, the script decides how many arguments have been passed and thus whether to use a long distance dialing service. If it finds four arguments (script name, pause dealy, number, LD-service), it branches to the "longdial" routine. If it finds not four (by falling through the if) and not three arguments (by taking the if !same branch), it then goes to a usage message routine. Depending upon the type of call, one of two routines passes the phone number off to the "dial" command, which actually instructs the modem to dial the number. Both dialing routines, then, branch to a common wait and see routine, which waits for up to 45 seconds for one of the two patterns to be matched. If the "CONNECT" pattern is matched, the script terminates and the user is (presumably) left to access the remote computer. If the "NO CARRIER" pattern is matched -- or if nothing is heard from the modem for 45 seconds -- the script branches to a wait routine where it "sleep"s for the time specified by the user -- and then tries to make the call again. - 63 - Comsh and CIS Comsh and CIS [Introduction] Comsh is, first and foremost, a terminal program meant to be used with the CompuServe Information and Executive Information Services. Many of the tricks Comsh performs are not in response to a user command, but in response to a command send from CIS. In this section, a description of what Comsh does in conjunction with CIS is given. [Cursor Positioning] One of the simpler things Comsh does is respond to the standard VIDTEX cursor positioning and screen clearning commands. Thus, Comsh is able to present menus nicely, play screen oriented games, and generally make full use of the services available on CIS/EIS. [Graphics] Comsh supports the medium and high resolution graphics that CIS/EIS is capable of generating. At the moment, the only software CIS has to generate graphics (beyond pure demos) are the high-res radar maps (GO AWX-4), and the stock plotting routines in MicroQuote. Note that you don't have to tell Comsh anything to get it into graphics modes; when CIS tells it to plot, Comsh plots. Of course, if you *don't* have a graphics display adapter, things aren't going to look too pretty... [File Transfers] Comsh supports the CIS A-protocol for file transfers. When you are in an XA (or public access) database, and give the UPL or DOW commands (or pick DOW off of a menu), you will be asked (by CIS) for the name of the file to transfer to/from. This filename is the name of the file on your computer that will be used; CIS transmits this name to COMSH, who in turn either uploads the file to CIS or downloads it from CIS. During the file transfer, Comsh prints out frequent status messages so you know that everything is proceding smoothly (or so that you know things aren't...). - 64 - Comsh and CIS